--- title: Operations and processes summary: End-to-end processing workflows behind the DBConnectionAPI endpoint surface. status: draft owner: Architecture last_reviewed: 2026-10-09 --- # Operations and processes DBConnectionAPI brokers database connection strings. For each request it resolves a template and a secure credential from the SAIF Environment API, composes a connection string, optionally proves that it connects with a constant probe query, caches the result in memory, and returns it. Three retrieval operations serve Oracle, SQL Server and PostgreSQL strings, and three Admin operations return the raw credential parts without validation or caching. This page is the operation catalog and hub. Each operation's detailed, step-by-step logic lives in its own page under `operations/`. ## Operation catalog | ID | Operation | Entry endpoint | Trigger | Owning component | Rules | | --- | --- | --- | --- | --- | --- | | [OP-01](operations/op-01-get-sql-connection-string.md) | Get SQL Server connection string | [`GET /v1/Connections/SQL/{server}/{instance}/{username}`](endpoints/connections.md#get-v1-connections-sql-server-instance-username) | Authorized HTTP request | `ConnectionManager.GetSqlConnectionString` | [BR-DBC-001](business-rules.md#br-dbc-001-serve-from-the-cache-when-the-key-is-present), [BR-DBC-002](business-rules.md#br-dbc-002-cache-key-format), [BR-DBC-009](business-rules.md#br-dbc-009-missing-secure-setting-returns-404), [BR-DBC-012](business-rules.md#br-dbc-012-four-probe-attempts-with-2%2C-3-and-5-second-backoff), [BR-DBC-013](business-rules.md#br-dbc-013-permanent-errors-stop-retrying), [BR-DBC-016](business-rules.md#br-dbc-016-other-final-failures-map-to-500), [BR-DBC-018](business-rules.md#br-dbc-018-probe-validity-definition), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) | | [OP-02](operations/op-02-get-postgresql-connection-string.md) | Get PostgreSQL connection string | [`GET /v1/Connections/PostgreSQL/{instance}/{username}`](endpoints/connections.md#get-v1-connections-postgresql-instance-username) | Authorized HTTP request | `ConnectionManager.GetPostgreSqlConnectionString` | [BR-DBC-006](business-rules.md#br-dbc-006-postgresql-credentials-ignore-the-server), [BR-DBC-020](business-rules.md#br-dbc-020-postgresql-strings-are-never-probed), [BR-DBC-021](business-rules.md#br-dbc-021-blank-postgresql-server-becomes-a-placeholder), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) | | [OP-03](operations/op-03-get-oracle-connection-string.md) | Get Oracle connection string | [`GET /v1/Connections/ORA/{instance}/{username}`](endpoints/connections.md#get-v1-connections-ora-instance-username) | Authorized HTTP request | `ConnectionManager.GetOracleConnectionString` | [BR-DBC-001](business-rules.md#br-dbc-001-serve-from-the-cache-when-the-key-is-present), [BR-DBC-012](business-rules.md#br-dbc-012-four-probe-attempts-with-2%2C-3-and-5-second-backoff), [BR-DBC-013](business-rules.md#br-dbc-013-permanent-errors-stop-retrying), [BR-DBC-015](business-rules.md#br-dbc-015-tns-alias-errors-map-to-400), [BR-DBC-016](business-rules.md#br-dbc-016-other-final-failures-map-to-500), [BR-DBC-019](business-rules.md#br-dbc-019-legacy-token-decoded-for-the-probe-only), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) | | [OP-04](operations/op-04-inspect-oracle-connection-info.md) | Inspect Oracle connection info | [`POST /v1/Admin/GetOracleConnectionInfo`](endpoints/admin.md#post-v1-admin-getoracleconnectioninfo) | Authorized HTTP request | `AdminController.GetOracleConnectionInfo` | [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials), [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) | | [OP-05](operations/op-05-inspect-postgresql-connection-info.md) | Inspect PostgreSQL connection info | [`POST /v1/Admin/GetPostgresConnectionInfo`](endpoints/admin.md#post-v1-admin-getpostgresconnectioninfo) | Authorized HTTP request | `AdminController.GetPostgresConnectionInfo` | [BR-DBC-006](business-rules.md#br-dbc-006-postgresql-credentials-ignore-the-server), [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials), [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) | | [OP-06](operations/op-06-inspect-sql-connection-info.md) | Inspect SQL Server connection info | [`POST /v1/Admin/GetSqlConnectionInfo`](endpoints/admin.md#post-v1-admin-getsqlconnectioninfo) | Authorized HTTP request | `AdminController.GetSqlConnectionInfo` | [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials), [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) | All 25 rules are cataloged on [Business rules](business-rules.md). ## Cross-operation flow diagram The following diagram visualizes how a retrieval request moves through the operations that share the connection manager. ```mermaid flowchart TD R["Incoming request"] --> A{"Authorized?"} A -->|"Denied"| Z["Authorization denial, status not visible in source"] A -->|"Authorized"| B{"Which surface?"} B -->|"Connections GET"| C["Audit log and key build"] B -->|"Admin POST"| H["OP-04, OP-05, OP-06:
read template and secure credential,
no cache, no probe"] C --> T["Read Environment API template (every request)"] T -->|"Template missing"| X["Unhandled/package error, status not visible in source"] T --> D{"Key cached?"} D -->|"Yes"| E["Return cached string"] D -->|"No"| F["Read secure credential, split at first pipe"] F -->|"Secure setting missing"| N["404 ConnectionManagerException"] F -->|"No pipe"| X2["Unhandled/package error, status not visible in source"] F --> G{"Database type"} G -->|"Oracle OP-03"| I["Probe SELECT 1 FROM DUAL, retry"] G -->|"SQL Server OP-01"| J["Probe SELECT 1, retry"] G -->|"PostgreSQL OP-02"| K["No probe"] I -->|"Final failure"| M["400 (Oracle) / 400* (SQL Server) or 500"] J -->|"Final failure"| M I --> L["Cache and return"] J --> L K --> L H -->|"Read fails"| X ``` ## Transaction boundaries | Operation | Unit of work | Commit point | Rollback trigger | | --- | --- | --- | --- | | [OP-01](operations/op-01-get-sql-connection-string.md) | `IUnitOfWorkFactory` (`SAIF.NetCore.NHibernate`), one throw-away unit per probe attempt | None; `Begin()` is never called and nothing is written | Not applicable | | [OP-03](operations/op-03-get-oracle-connection-string.md) | `IUnitOfWorkFactory` (`SAIF.NetCore.NHibernate`), one throw-away unit per probe attempt | None; nothing is written | Not applicable | OP-02, OP-04, OP-05 and OP-06 perform no database access. The API writes no data in any operation. ## Failure and edge-case behavior - Secure setting missing (OP-01, OP-02, OP-03): 404 from `ConnectionManagerException`, rendered by package middleware (`DynamicErrorHandler`†) ([BR-DBC-009](business-rules.md#br-dbc-009-missing-secure-setting-returns-404)) - Oracle TNS alias not resolved: 400 through the same middleware ([BR-DBC-015](business-rules.md#br-dbc-015-tns-alias-errors-map-to-400)) - Probe failure after four attempts, invalid credentials, database unavailable or network interruption: 500 through the same middleware ([BR-DBC-016](business-rules.md#br-dbc-016-other-final-failures-map-to-500)) - Credential without a pipe on a retrieval request, or a missing template: unhandled exception; the status is not visible in source** ([BR-DBC-010](business-rules.md#br-dbc-010-credential-split-at-the-first-pipe%2C-unguarded)) - Credential without a pipe on an Admin request: 200 with an `Error` entry ([BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200)) - Authorization failure: produced by the package authorization handler†; the status is not visible in source** ([BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint)) - Cache entries never expire, so a rotated credential is served stale until the process restarts ([BR-DBC-004](business-rules.md#br-dbc-004-cache-entries-never-expire)) ## Related documentation - [API index](index.md) - [Overview](overview.md) - [Architecture](architecture.md) - [Hosting pipeline](hosting-pipeline.md) - [Endpoints](endpoints.md) - [Authentication and authorization](authentication-authorization.md) - [Dependencies](dependencies.md) - [Configuration](configuration.md) - [Business rules](business-rules.md) - [Data model](data-model.md) - [Operational runbook](operational-runbook.md) - [Tech debt](tech-debt.md) > **Note:** Statements marked with `†` are derived from dependency library > documentation via the Legends CLI. Statements marked with `*` were inferred > from code structure or contextual evidence. Statements marked with `**` could > not be confirmed; treat as unknown until verified. ## Sources - DBConnectionAPI/DBConnectionAPI/Controllers/ConnectionsController.cs - DBConnectionAPI/DBConnectionAPI/Controllers/AdminController.cs - DBConnectionAPI/DBConnectionAPI/Services/ConnectionManager.cs - DBConnectionAPI/DBConnectionAPI/Services/IConnectionManager.cs - DBConnectionAPI/DBConnectionAPI/Exceptions/ConnectionManagerException.cs - DBConnectionAPI/DBConnectionAPI/Startup.cs